The amarok Smart DJ plug-in
"Because you knew your own radio station was there, buried in your music collection."
by Rudd-O
distributed under the GNU GPL, version 2


	What the heck is this? What's this useful for?

You already know how powerful amaroK's search and playlist management capabilities are.  Just imagine how cool it would be to find songs that sounds like the one you're listening to, right now.  Similar genre, similar sound, similar tempo.  Now imagine this: you start playing one of your favorite songs, and, as time goes by, amaroK adds similar songs to your playlist, maintaining the mood.  Not just "songs someone else found similar", but songs that truly sound alike, same genre, same mood, same tempo.

That's what Smart DJ does.  Start with a good song, and let amaroK Smart DJ's Auto DJ do the rest.  Or scratch on your favorite DJ program, and Smart DJ will let you find what to play next real quick.  Or build fantastic playlists, sorted by tempo, or song similarity, the sky is the limit.  Or simply take any of Smart DJ's suggestions for similar songs in the Context browser.  That's the greatest way to discover an entire music collection.

You'll also be able to search for similar songs manually.  You'll also be able to see the most similar songs in the Context Browser.  You'll also be able to see the tempo of your songs in your playlist (by applying the supplied patch).  You'll also be able to tap the tempo of your songs, if the tempo was wrong.

This plug-in is perfect for people who hate making playlists, or hate the predictibility of hearing a playlist, or hate amaroK's Dynamic mode tendency to add songs that ruin the mood.  This plug-in is also for people who want to discover the lost and unknown good songs in their own collection.  Finally, this plug-in is perfect for DJs who want to plan good sets of songs and playlists for live performance.


	So, what features does this have?

- Song analysis based on average intensity across 30 different frequency bands
- Song analysis based on tempo
- Similarity calculation based on weighted sum of normalized tempo/frequency band interference distances
- Edit tempo of already analyzed and not analyzed songs, with phase detection on analyzed songs for maximum accuracy
- Auto DJ: add compatible tracks to playlist, based on the entire collection or a Dynamic playlist-defined subset, with configurable tempo/music style similarity weightings
- Similar song manual search


	So, how do I use this?

First, read "What do I need to use this plug-in?" below.

Did you read it?

...okay, so you read it and obeyed it.  Let's get to using this.

To use this, install it through your Scripts manager in amaroK, then select it from the list and click Run.  If everything is OK, you'll see a yellow status message in the playlist window saying "Smart DJ is analyzing your collection".  Be very, very patient, because analyzing each song takes a minimum of 20 seconds.

Whenever you play a song while watching the Current tab in the Context Browser, Smart DJ will add its list of suggestions (Similar Tracks) right above the Favorite Tracks box.  If a song has not been analyzed yet, do not worry: Smart DJ will quietly bump it to the top of its to-do list, and in a few seconds, you'll see the Similar Tracks box appear in the Current tab.

The following functionality requires you to have certain GUI components installed on your computer.  See below, in the requirements section, for more information on the subject.

You can, as well, directly right-click on a song in your playlist and select:
	"Smart DJ"->"Find songs similar to selection..."
to get a list of songs sorted by similarity against the one you selected.

To use Auto DJ, select the plug-in in the Scripts manager and click Configure.  The Auto DJ options are self-explanatory: all you need to do is enable it, set the options you want (the defaults are very good starters), and start playing a song of your choice.  Auto DJ will analyze the song you're playing (or the last song in the playlist, depending on your chosen settings) and start locating similar files to add to the playlist.  Auto DJ will not add songs already on your playlist, or songs that Auto DJ added to the playlist but you removed.  You can let Auto DJ choose songs from your entire collection, or from among any of your saved smart playlists.  You can also let Auto DJ make a big playlist even before starting to play: all you have to do is let Auto DJ you want to use the last song in your playlist as your reference, and set a large number of songs to be added.

If you want to know how far along the analysis is, you can select the plug-in in the Scripts manager and click Configure, a small window with a progress bar will appear.

Tip: although you can't normally see the tempo of songs in the standard version of amaroK, a special patch is distributed with this plug-in.  If you know how to patch amaroK's source code and recompile it from scratch, you can apply the patch, which will add a new column named "Tempo" in the playlist.


	How does this wonderful wonder work?

Smart DJ does this by performing magic... ehhrmm... running a series of analysis on the songs in your collection, collecting tempo and frequency distribution from each song and storing the information in the collection database.  This process is assisted by songanalysis, another program.  Songanalysis computes both tempo and relative intensity across 30 frequency bands.  This is later compared against the entire collection (pretty quickly, I must say, thanks to your favorite SQL engine), and a compatibility score is computed for each song.


	What do I need to use this plug-in?

You need a variety of things.  Others aren't needed, but greatly improve your experience with Smart DJ.  Here's the list (optional items are marked 'optional'):

- amaroK 1.3.1 or higher
- a working installation of Python
- attr (getfattr and setfattr commands)
- a Python package called python-extattr
- a Python package called python-commandsplus
- the songanalysis program (which analyzes the songs)
- (optional, highly desirable ) mpg321 (to analyze MP3)
- (optional, highly desirable) ogg321 (to analyze Ogg Vorbis files)
- (optional, highly desirable) PyQt
- (optional, highly desirable) support for extended attributes on your file systems
- (future optional requirements) PyKDE

Of those, all are available on the Internet, as source packages
and as precompiled RPM packages.

Optional activities:

* Install mpg321 and ogg321
The program that performs the music analysis, songanalysis, does not read MP3 or Ogg Vorbis files directly.  songanalysis requires mpg321 and ogg321 to be present in order to analyze MP3 and Ogg Vorbis files, respectively.  I guess you could make use of Smart DJ with only WAV files... but then again, I'm guessing you own lots more MP3 than WAV files.

* Install PyQt
This plug-in requires the PyQt Python bindings for Qt for the user interface.  You'll probably find it easy to install PyQt since you already have amaroK and hence you have Qt installed.  Basically, without PyQt, no user interface, no Auto DJ.  Only analysis and a small box in the Context browser.

* Patch amaroK with the included patch named amarok-show-tempo.diff
This will let you see song tempo in a playlist column.  This is very convenient.

* Enable extended attribute usage on your computer
Note that extended attributes are /optional/.  But not enabling them may prove detrimental to this package's performance.  What is /required/ is the presence of the python-extattr package, along with the getfattr and setfattr commands.  See below for easy instructions on enabling extended attributes.


	How do I turn on this "extended attributes" thing?

That's rather easy.

Each file system needs to be mounted with an extra option
called 'user_xattr'.  To see if this is supported on your
system, issue the following command on a command prompt,
as root:

   mount / -o remount,user_xattr

If you do not get any error message, then you're all set: you
have extended attribute support.  Do the command for all other
file systems where you store your songs (use the 'mount'
command alone to find out about the rest of your file systems).

To make this change permanent (across system restarts), edit
the /etc/fstab file and change the mount options field (for
each file system where you have your songs), adding
'user_xattr' where appropriate, or replacing the 'defaults'
keyword by 'user_xattr'.

By the way, this will be notoriously impossible to do if you're
using a Windows (VFAT) file system to store your music files.
VFAT file systems have no support for extended attributes at
all.  Do yourself a favor and reformat your disk to use either
ReiserFS, ext3 or another true UNIX file system.

Remember, extended attributes are optional.


	Why are extended attributes used?

Analyzing a song takes quite a while (about 30 seconds for each
song).

If you moved your song files to a new directory, and the
analysis results were stored only in the collection database,
this plug-in would need to analyze each song again, because
since the path to the file changed, there would be no way to
correlate the already stored information to the new file
location.

So, to alleviate this problem, this plug-in stores the analysis
results on extended attributes, so when a file is about to be
analyzed we can check whether the analysis was already
performed on that file and then simply collect the analysis
results, saving you time and electricity.

This is not infallible, of course.  If you had file /a/b/c.mp3
and you delete it, replacing it with another file at exactly
the same /a/b/c.mp3 location but a different content (and, of
course, different attributes) this plug-in won't detect the
special case.  There is a solution, but I'm quite lazy to
start working on it just about right now.

And, by the way, if you actually rename a file on disk, or move
it somewhere else (in your collection folders, of course) even
though amaroK would still show that file on your collection
browser, you would lose your statistics for that song (play
counter, last play date and rating).  This is a bug in amaroK.

I'm working on a long-term solution to this problem.